<html>
<!-- (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Hewlett-Packard Development Company, LP -->
<head>
<title>Jena2 HSQL HowTo</title>
<link href="../styles/doc.css" rel="stylesheet" type="text/css" />
</head>
<body>

<h1>HowTo Use HSQLDB with Jena2</h1>

<h2>What is HSQLDB?</h2>

<p><a href="http://www.hsqldb.org/">HSQLDB</a> (also known as Hypersonic or HSQL), 
is a lightweight, 100% Java SQL Database Engine. Used with Jena, it provides a 
simple way to give persistence to RDF data by using HSQLDB within the 
application JVM, using the file system for persistence.&nbsp; HSQLDB can also 
run as a database server, handling connections from different JVMs, and also as 
a purely in-memory engine.</p>
<p>Using it within one application JVM, and using file-based persistence, is the 
most useful mode with Jena. The application should manage internal concurrency 
with <a href="../how-to/concurrency.html">MRSW (multi-reader, single-writer) 
locking</a>, or Java synchronized (which is single reader, single writer 
locking), because HSQLDB does not support full transaction isolation. </p>

<h2>Download and Installation of HSQLDB</h2>

<p><a href="http://sourceforge.net/project/showfiles.php?group_id=23316">
Download HSQLDB</a> from SourceForge, unpack the zip file and put the <code>hsqldb.jar</code> 
file on the application classpath. This includes the JDBC driver and the 
database engine.</p>

<h2>Connecting Your Jena Program to HSQLDB</h2>
<h3>JDBC URLs</h3>
<p>JDBC URLs for HSQLDB look like the following:</p>
<ul>
  <li><code>jdbc:hsqldb:file:</code><i><code>filepathname</code></i> : 
  File-persistence</li>
  <li><code>jdbc:hsqldb:hsql:</code><i><code>DB_NAME</code></i>: database server</li>
  <li><code>jdbc:hsqldb:mem:</code><i><code>DBname</code></i>: in-memory only</li>
</ul>
<p>By default, for file-persistence, the user name is &quot;sa&quot; and the password is 
&quot;&quot;. See the HSQLDB documentation for further details. </p>
<p>The database JDBC driver is class <code>org.hsqldb.jdbcDriver</code>.&nbsp; 
Compare this to Derby where the driver changes but the URL is the same for 
server or embedded use.</p>
<p>The Jena driver name is HSQL.</p>
<p>Persistent models are <a href="creating-db-models.html">created</a> in the 
same way for any database system: </p>
<blockquote>
  <ol>
    <li>Load the JDBC driver. This enables the Jena program to communicate with 
    the database instance.</li>
    <li>Create a database connection. This creates a Java object for a database 
    connection.</li>
    <li>Create a ModelMaker for the database</li>
    <li>Create a Model for existing or new data.</li>
  </ol>
</blockquote>

<p>These steps are illustrated in the following Java code.</p>

<pre class="box">
String className = &quot;org.hsqldb.jdbcDriver&quot;;       // path of driver class
Class.forName (className);                        // Load the Driver
String DB_URL =    &quot;jdbc:hsqldb:file:<i>filename</i>&quot;;   // URL of database 
String DB_USER =   &quot;sa&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   // database user id
String DB_PASSWD = &quot;&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;    // database password
String DB =&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &quot;HSQL&quot;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;    // database type

// Create database connection
IDBConnection conn = new DBConnection ( DB_URL, DB_USER, DB_PASSWD, DB );
ModelMaker maker = ModelFactory.createModelRDBMaker(conn) ;

// create or open the default model
Model model = maker.createDefaultModel();

// Close the database connection
conn.close();
</pre>
    
<h2>HSQLDB Notes</h2>
<p>HSQLDB does not support full ACID transactions; the application can read 
uncommitted updates from other transactions. The application should 
use locking within the application, such as <a href="../how-to/concurrency.html">MRSW 
locking</a> or provide it's own locking, to ensure that updates and reads do not overlap.</p>
<p>Jena does not compact the database because it does not know when the database 
is no longer required by the application - the application must arrange to do 
this itself. This can be by using the database manager (<code>org.hsqldb.util.DatabaseManager</code>) 
to compact the database</p>
<p>Or the application can do it by either:</p>
<ol>
  <li>Get the Jena driver , cast to Driver_HSQL and call .shutdown().</li>
  <li>Get the SQL connection and execute &quot;SHUTDOWN COMPACT&quot; as an SQL 
  command.</li>
</ol>


</body>
</html>
